<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>GeoDjango Forms API &mdash; Django 1.7.8.dev20150401230226 documentation</title>
    
    <link rel="stylesheet" href="../../../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../../',
        VERSION:     '1.7.8.dev20150401230226',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../../_static/doctools.js"></script>
    <link rel="top" title="Django 1.7.8.dev20150401230226 documentation" href="../../../index.html" />
    <link rel="up" title="GeoDjango" href="index.html" />
    <link rel="next" title="GeoQuerySet API Reference" href="geoquerysets.html" />
    <link rel="prev" title="GeoDjango Database API" href="db-api.html" />



 
<script type="text/javascript" src="../../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../../templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);
</script>


  </head>
  <body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../../../index.html">Django 1.7.8.dev20150401230226 documentation</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../../../index.html">Home</a>  |
        <a title="Table of contents" href="../../../contents.html">Table of contents</a>  |
        <a title="Global index" href="../../../genindex.html">Index</a>  |
        <a title="Module index" href="../../../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="db-api.html" title="GeoDjango Database API">previous</a>
     |
    <a href="../../index.html" title="API Reference" accesskey="U">up</a>
   |
    <a href="geoquerysets.html" title="GeoQuerySet API Reference">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="ref-contrib-gis-forms-api">
            
  <div class="section" id="s-module-django.contrib.gis.forms">
<span id="s-geodjango-forms-api"></span><span id="s-ref-gis-forms-api"></span><span id="module-django.contrib.gis.forms"></span><span id="geodjango-forms-api"></span><span id="ref-gis-forms-api"></span><h1>GeoDjango Forms API<a class="headerlink" href="#module-django.contrib.gis.forms" title="Permalink to this headline">¶</a></h1>
<div class="versionadded">
<span class="title">New in Django 1.6.</span> </div>
<p>GeoDjango provides some specialized form fields and widgets in order to visually
display and edit geolocalized data on a map. By default, they use
<a class="reference external" href="http://openlayers.org/">OpenLayers</a>-powered maps, with a base WMS layer provided by <a class="reference external" href="http://www.metacarta.com/">Metacarta</a>.</p>
<div class="section" id="s-field-arguments">
<span id="field-arguments"></span><h2>Field arguments<a class="headerlink" href="#field-arguments" title="Permalink to this headline">¶</a></h2>
<p>In addition to the regular <a class="reference internal" href="../../forms/fields.html#core-field-arguments"><em>form field arguments</em></a>,
GeoDjango form fields take the following optional arguments.</p>
<div class="section" id="s-srid">
<span id="srid"></span><h3><tt class="docutils literal"><span class="pre">srid</span></tt><a class="headerlink" href="#srid" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="django.contrib.gis.forms.Field.srid">
<tt class="descclassname">Field.</tt><tt class="descname">srid</tt><a class="headerlink" href="#django.contrib.gis.forms.Field.srid" title="Permalink to this definition">¶</a></dt>
<dd><p>This is the SRID code that the field value should be transformed to. For
example, if the map widget SRID is different from the SRID more generally
used by your application or database, the field will automatically convert
input values into that SRID.</p>
</dd></dl>

</div>
<div class="section" id="s-geom-type">
<span id="geom-type"></span><h3><tt class="docutils literal"><span class="pre">geom_type</span></tt><a class="headerlink" href="#geom-type" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="django.contrib.gis.forms.Field.geom_type">
<tt class="descclassname">Field.</tt><tt class="descname">geom_type</tt><a class="headerlink" href="#django.contrib.gis.forms.Field.geom_type" title="Permalink to this definition">¶</a></dt>
<dd><p>You generally shouldn&#8217;t have to set or change that attribute which should
be setup depending on the field class. It matches the OpenGIS standard
geometry name.</p>
</dd></dl>

</div>
</div>
<div class="section" id="s-form-field-classes">
<span id="form-field-classes"></span><h2>Form field classes<a class="headerlink" href="#form-field-classes" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-geometryfield">
<span id="geometryfield"></span><h3><tt class="docutils literal"><span class="pre">GeometryField</span></tt><a class="headerlink" href="#geometryfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.contrib.gis.forms.GeometryField">
<em class="property">class </em><tt class="descname">GeometryField</tt><a class="headerlink" href="#django.contrib.gis.forms.GeometryField" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

</div>
<div class="section" id="s-pointfield">
<span id="pointfield"></span><h3><tt class="docutils literal"><span class="pre">PointField</span></tt><a class="headerlink" href="#pointfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.contrib.gis.forms.PointField">
<em class="property">class </em><tt class="descname">PointField</tt><a class="headerlink" href="#django.contrib.gis.forms.PointField" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

</div>
<div class="section" id="s-linestringfield">
<span id="linestringfield"></span><h3><tt class="docutils literal"><span class="pre">LineStringField</span></tt><a class="headerlink" href="#linestringfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.contrib.gis.forms.LineStringField">
<em class="property">class </em><tt class="descname">LineStringField</tt><a class="headerlink" href="#django.contrib.gis.forms.LineStringField" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

</div>
<div class="section" id="s-polygonfield">
<span id="polygonfield"></span><h3><tt class="docutils literal"><span class="pre">PolygonField</span></tt><a class="headerlink" href="#polygonfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.contrib.gis.forms.PolygonField">
<em class="property">class </em><tt class="descname">PolygonField</tt><a class="headerlink" href="#django.contrib.gis.forms.PolygonField" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

</div>
<div class="section" id="s-multipointfield">
<span id="multipointfield"></span><h3><tt class="docutils literal"><span class="pre">MultiPointField</span></tt><a class="headerlink" href="#multipointfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.contrib.gis.forms.MultiPointField">
<em class="property">class </em><tt class="descname">MultiPointField</tt><a class="headerlink" href="#django.contrib.gis.forms.MultiPointField" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

</div>
<div class="section" id="s-multilinestringfield">
<span id="multilinestringfield"></span><h3><tt class="docutils literal"><span class="pre">MultiLineStringField</span></tt><a class="headerlink" href="#multilinestringfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.contrib.gis.forms.MultiLineStringField">
<em class="property">class </em><tt class="descname">MultiLineStringField</tt><a class="headerlink" href="#django.contrib.gis.forms.MultiLineStringField" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

</div>
<div class="section" id="s-multipolygonfield">
<span id="multipolygonfield"></span><h3><tt class="docutils literal"><span class="pre">MultiPolygonField</span></tt><a class="headerlink" href="#multipolygonfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.contrib.gis.forms.MultiPolygonField">
<em class="property">class </em><tt class="descname">MultiPolygonField</tt><a class="headerlink" href="#django.contrib.gis.forms.MultiPolygonField" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

</div>
<div class="section" id="s-geometrycollectionfield">
<span id="geometrycollectionfield"></span><h3><tt class="docutils literal"><span class="pre">GeometryCollectionField</span></tt><a class="headerlink" href="#geometrycollectionfield" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.contrib.gis.forms.GeometryCollectionField">
<em class="property">class </em><tt class="descname">GeometryCollectionField</tt><a class="headerlink" href="#django.contrib.gis.forms.GeometryCollectionField" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

</div>
</div>
<div class="section" id="s-module-django.contrib.gis.widgets">
<span id="s-form-widgets"></span><span id="module-django.contrib.gis.widgets"></span><span id="form-widgets"></span><h2>Form widgets<a class="headerlink" href="#module-django.contrib.gis.widgets" title="Permalink to this headline">¶</a></h2>
<p>GeoDjango form widgets allow you to display and edit geographic data on a
visual map.
Note that none of the currently available widgets supports 3D geometries, hence
geometry fields will fallback using a simple <tt class="docutils literal"><span class="pre">Textarea</span></tt> widget for such data.</p>
<div class="section" id="s-widget-attributes">
<span id="widget-attributes"></span><h3>Widget attributes<a class="headerlink" href="#widget-attributes" title="Permalink to this headline">¶</a></h3>
<p>GeoDjango widgets are template-based, so their attributes are mostly different
from other Django widget attributes.</p>
<dl class="attribute">
<dt id="django.contrib.gis.widgets.BaseGeometryWidget.geom_type">
<tt class="descclassname">BaseGeometryWidget.</tt><tt class="descname">geom_type</tt><a class="headerlink" href="#django.contrib.gis.widgets.BaseGeometryWidget.geom_type" title="Permalink to this definition">¶</a></dt>
<dd><p>The OpenGIS geometry type, generally set by the form field.</p>
</dd></dl>

<dl class="attribute">
<dt id="django.contrib.gis.widgets.BaseGeometryWidget.map_height">
<tt class="descclassname">BaseGeometryWidget.</tt><tt class="descname">map_height</tt><a class="headerlink" href="#django.contrib.gis.widgets.BaseGeometryWidget.map_height" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="attribute">
<dt id="django.contrib.gis.widgets.BaseGeometryWidget.map_width">
<tt class="descclassname">BaseGeometryWidget.</tt><tt class="descname">map_width</tt><a class="headerlink" href="#django.contrib.gis.widgets.BaseGeometryWidget.map_width" title="Permalink to this definition">¶</a></dt>
<dd><p>Height and width of the widget map (default is 400x600).</p>
</dd></dl>

<dl class="attribute">
<dt id="django.contrib.gis.widgets.BaseGeometryWidget.map_srid">
<tt class="descclassname">BaseGeometryWidget.</tt><tt class="descname">map_srid</tt><a class="headerlink" href="#django.contrib.gis.widgets.BaseGeometryWidget.map_srid" title="Permalink to this definition">¶</a></dt>
<dd><p>SRID code used by the map (default is 4326).</p>
</dd></dl>

<dl class="attribute">
<dt id="django.contrib.gis.widgets.BaseGeometryWidget.display_raw">
<tt class="descclassname">BaseGeometryWidget.</tt><tt class="descname">display_raw</tt><a class="headerlink" href="#django.contrib.gis.widgets.BaseGeometryWidget.display_raw" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean value specifying if a textarea input showing the serialized
representation of the current geometry is visible, mainly for debugging
purposes (default is <tt class="docutils literal"><span class="pre">False</span></tt>).</p>
</dd></dl>

<dl class="attribute">
<dt id="django.contrib.gis.widgets.BaseGeometryWidget.supports_3d">
<tt class="descclassname">BaseGeometryWidget.</tt><tt class="descname">supports_3d</tt><a class="headerlink" href="#django.contrib.gis.widgets.BaseGeometryWidget.supports_3d" title="Permalink to this definition">¶</a></dt>
<dd><p>Indicates if the widget supports edition of 3D data (default is <tt class="docutils literal"><span class="pre">False</span></tt>).</p>
</dd></dl>

<dl class="attribute">
<dt id="django.contrib.gis.widgets.BaseGeometryWidget.template_name">
<tt class="descclassname">BaseGeometryWidget.</tt><tt class="descname">template_name</tt><a class="headerlink" href="#django.contrib.gis.widgets.BaseGeometryWidget.template_name" title="Permalink to this definition">¶</a></dt>
<dd><p>The template used to render the map widget.</p>
</dd></dl>

<p>You can pass widget attributes in the same manner that for any other Django
widget. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.contrib.gis</span> <span class="kn">import</span> <span class="n">forms</span>

<span class="k">class</span> <span class="nc">MyGeoForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
    <span class="n">point</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">PointField</span><span class="p">(</span><span class="n">widget</span><span class="o">=</span>
        <span class="n">forms</span><span class="o">.</span><span class="n">OSMWidget</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s">&#39;map_width&#39;</span><span class="p">:</span> <span class="mi">800</span><span class="p">,</span> <span class="s">&#39;map_height&#39;</span><span class="p">:</span> <span class="mi">500</span><span class="p">}))</span>
</pre></div>
</div>
</div>
<div class="section" id="s-widget-classes">
<span id="widget-classes"></span><h3>Widget classes<a class="headerlink" href="#widget-classes" title="Permalink to this headline">¶</a></h3>
<p><tt class="docutils literal"><span class="pre">BaseGeometryWidget</span></tt></p>
<dl class="class">
<dt id="django.contrib.gis.widgets.BaseGeometryWidget">
<em class="property">class </em><tt class="descname">BaseGeometryWidget</tt><a class="headerlink" href="#django.contrib.gis.widgets.BaseGeometryWidget" title="Permalink to this definition">¶</a></dt>
<dd><p>This is an abstract base widget containing the logic needed by subclasses.
You cannot directly use this widget for a geometry field.
Note that the rendering of GeoDjango widgets is based on a template,
identified by the <a class="reference internal" href="#django.contrib.gis.widgets.BaseGeometryWidget.template_name" title="django.contrib.gis.widgets.BaseGeometryWidget.template_name"><tt class="xref py py-attr docutils literal"><span class="pre">template_name</span></tt></a> class attribute.</p>
</dd></dl>

<p><tt class="docutils literal"><span class="pre">OpenLayersWidget</span></tt></p>
<dl class="class">
<dt id="django.contrib.gis.widgets.OpenLayersWidget">
<em class="property">class </em><tt class="descname">OpenLayersWidget</tt><a class="headerlink" href="#django.contrib.gis.widgets.OpenLayersWidget" title="Permalink to this definition">¶</a></dt>
<dd><p>This is the default widget used by all GeoDjango form fields.
<tt class="docutils literal"><span class="pre">template_name</span></tt> is <tt class="docutils literal"><span class="pre">gis/openlayers.html</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">OpenLayersWidget</span></tt> and <a class="reference internal" href="#django.contrib.gis.widgets.OSMWidget" title="django.contrib.gis.widgets.OSMWidget"><tt class="xref py py-class docutils literal"><span class="pre">OSMWidget</span></tt></a> use the <tt class="docutils literal"><span class="pre">openlayers.js</span></tt> file
hosted on the <tt class="docutils literal"><span class="pre">openlayers.org</span></tt> Web site. This works for basic usage
during development, but isn&#8217;t appropriate for a production deployment as
<tt class="docutils literal"><span class="pre">openlayers.org/api/</span></tt> has no guaranteed uptime and runs on a slow server.
You are therefore advised to subclass these widgets in order to specify
your own version of the <tt class="docutils literal"><span class="pre">openlayers.js</span></tt> file in the <tt class="docutils literal"><span class="pre">js</span></tt> property of
the inner <tt class="docutils literal"><span class="pre">Media</span></tt> class (see <a class="reference internal" href="../../../topics/forms/media.html#assets-as-a-static-definition"><em>Assets as a static definition</em></a>). You
can host a copy of <tt class="docutils literal"><span class="pre">openlayers.js</span></tt>
<a class="reference external" href="http://docs.openlayers.org/library/deploying.html">tailored to your needs</a> on your own server or refer to a copy from a
content-delivery network like <a class="reference external" href="http://cdnjs.com/">http://cdnjs.com/</a>. This will also allow
you to serve the JavaScript file(s) using the <tt class="docutils literal"><span class="pre">https</span></tt> protocol if needed.</p>
</dd></dl>

<p><tt class="docutils literal"><span class="pre">OSMWidget</span></tt></p>
<dl class="class">
<dt id="django.contrib.gis.widgets.OSMWidget">
<em class="property">class </em><tt class="descname">OSMWidget</tt><a class="headerlink" href="#django.contrib.gis.widgets.OSMWidget" title="Permalink to this definition">¶</a></dt>
<dd><p>This widget uses an OpenStreetMap base layer (Mapnik) to display geographic
objects on.
<tt class="docutils literal"><span class="pre">template_name</span></tt> is <tt class="docutils literal"><span class="pre">gis/openlayers-osm.html</span></tt>.</p>
<p>The <a class="reference internal" href="#django.contrib.gis.widgets.OpenLayersWidget" title="django.contrib.gis.widgets.OpenLayersWidget"><tt class="xref py py-class docutils literal"><span class="pre">OpenLayersWidget</span></tt></a> note about JavaScript file hosting above also
applies here. See also this <a class="reference external" href="https://help.openstreetmap.org/questions/10920/how-to-embed-a-map-in-my-https-site">FAQ answer</a> about <tt class="docutils literal"><span class="pre">https</span></tt> access to map
tiles.</p>
</dd></dl>

</div>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../../../contents.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">GeoDjango Forms API</a><ul>
<li><a class="reference internal" href="#field-arguments">Field arguments</a><ul>
<li><a class="reference internal" href="#srid"><tt class="docutils literal"><span class="pre">srid</span></tt></a></li>
<li><a class="reference internal" href="#geom-type"><tt class="docutils literal"><span class="pre">geom_type</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#form-field-classes">Form field classes</a><ul>
<li><a class="reference internal" href="#geometryfield"><tt class="docutils literal"><span class="pre">GeometryField</span></tt></a></li>
<li><a class="reference internal" href="#pointfield"><tt class="docutils literal"><span class="pre">PointField</span></tt></a></li>
<li><a class="reference internal" href="#linestringfield"><tt class="docutils literal"><span class="pre">LineStringField</span></tt></a></li>
<li><a class="reference internal" href="#polygonfield"><tt class="docutils literal"><span class="pre">PolygonField</span></tt></a></li>
<li><a class="reference internal" href="#multipointfield"><tt class="docutils literal"><span class="pre">MultiPointField</span></tt></a></li>
<li><a class="reference internal" href="#multilinestringfield"><tt class="docutils literal"><span class="pre">MultiLineStringField</span></tt></a></li>
<li><a class="reference internal" href="#multipolygonfield"><tt class="docutils literal"><span class="pre">MultiPolygonField</span></tt></a></li>
<li><a class="reference internal" href="#geometrycollectionfield"><tt class="docutils literal"><span class="pre">GeometryCollectionField</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-django.contrib.gis.widgets">Form widgets</a><ul>
<li><a class="reference internal" href="#widget-attributes">Widget attributes</a></li>
<li><a class="reference internal" href="#widget-classes">Widget classes</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h3>Browse</h3>
  <ul>
    
      <li>Prev: <a href="db-api.html">GeoDjango Database API</a></li>
    
    
      <li>Next: <a href="geoquerysets.html">GeoQuerySet API Reference</a></li>
    
  </ul>
  <h3>You are here:</h3>
  <ul>
      <li>
        <a href="../../../index.html">Django 1.7.8.dev20150401230226 documentation</a>
        
          <ul><li><a href="../../index.html">API Reference</a>
        
          <ul><li><a href="../index.html"><tt class="docutils literal"><span class="pre">contrib</span></tt> packages</a>
        
          <ul><li><a href="index.html">GeoDjango</a>
        
        <ul><li>GeoDjango Forms API</li></ul>
        </li></ul></li></ul></li></ul>
      </li>
  </ul>

  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="../../../_sources/ref/contrib/gis/forms-api.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="../../../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">Apr 02, 2015</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="db-api.html" title="GeoDjango Database API">previous</a>
     |
    <a href="../../index.html" title="API Reference" accesskey="U">up</a>
   |
    <a href="geoquerysets.html" title="GeoQuerySet API Reference">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>